═══ 1. Before you do anything ! ═══

FBiMon.sys is a FREEWARE driver for OS/2. It means that you can copy it and 
give it to your friends as long as every file are given and no changes are made 
to any file. FBiMon.sys has been developped at first for my needs, but I would 
be very happy if it could help anyone. I make no warranty of any kind about 
FBiMon.sys, and so I am not responsible of any use of it, nor am I responsible 
for any damage it could do. YOU USE IT AT YOUR OWN RISK ! 

I strongly recommend that you test it before incorporating it in your system. 
FBiMon.sys has been made to be stable on my system, so I cannot guarantee that 
it will work on yours. To avoid a loss of data, you may boot on floppy and 
tries FBiMon.sys from there. See the "Testing the driver" section. 


═══ 2. Introduction ═══

About FBiMon.sys 

FBiMon.sys is a driver for the Hercule monochrome adapter under OS/2 2.0 and 
higher, for a system with two monitors, with the Hercule monitor as the 
secondary monitor. 

The driver shipped with OS/2 does not provide a good access to the secondary 
monitor (imho). First, only one screen is refreshed at a time, and second, you 
have access only to text mode. This is due to the fact that OS/2 does not 
really support an Hercule card but an MDA card. 

FBiMon.sys allows you to use both screens at the same time and is able to 
either initiate a text mode or a graphic mode. It is also possible to change 
the cursor aspect, to enable blinking characters and to test a vertical 
scanline. 

As time goes, there will be more functions added to FBiMon.sys. 

FBiMon.sys is a FREEWARE driver for OS/2. It means that you can copy it and 
give it to your friends as long as every file are given and no changes are made 
to any file. FBiMon.sys has been developped at first for my needs, but I would 
be very happy if it could help anyone. I make no warranty of any kind about 
FBiMon.sys, and so I am not responsible of any use of it, nor am I responsible 
for any damage it could do. YOU USE IT AT YOUR OWN RISK ! 

Current version of the driver is version 0.02. It is still in beta stage but is 
fairly stable. There should not be any major bugs (so far I hope !). 


═══ 3. Installation ═══

How to install FBiMon.sys 

To install FBiMon.sys just follow these steps 

     Copy the FBIMON package in a directory of your choice 

     Add this line at the end of your CONFIG.SYS file : 

                          DEVICE = X : \ PATH \ FBIMON . SYS
      Where 

        -  X: is the drive where the FBIMON package has been installed 
        -  PATH is the path name where the package is located on the driver 

     Reboot your computer to enable the changes 

 You should see an FBi logo during OS/2 startup 


═══ 4. The making of ═══

To bring this driver to you, I had to use these applications : 

     EPM, the editor shipped with OS/2, the best editor (imho) ! 
     ALP, an unsupported assembler from IBM, maybe the only assembler running 
      completely under OS/2 
     LINK, shipped with OS/2 
     HeD by Jnk, an excellent hexadecimal editor, the best one (imho) 
     IPFC, to create this INF file 

 To create software using the driver, I also had to use these applications : 

     TmT Pascal Lite compiler, a really good pascal compiler for OS/2 and DOS 
     EMX GCC, the GNU C/C++ compiler for OS/2 (used to create a Rexx dll) 

 This driver has been entirely written in assembly langage (16 bit) 


═══ 5. Testing the driver ═══

How to test FBiMon.sys 

The way FBiMon.sys has been concieved allows you to test it with simple 
commands. FBiMon.sys is packaged with some *.BIN files. These files contain 
commands for the FBiMon.sys driver. To send them to the driver, just type : 

                          COPY  XXXXXXX . BIN  FBIMON $
where XXXXXXX.BIN is one of the following files : 

 FileName            Contents 
 HrcTxt.bin          Initializes the text mode 
 HrcGfx.bin          Initializes the graphic mode 
 HrcTest.bin         Initializes the graphic mode and draws a point in each 
                     corner of the screen 
 These are very short files, but they are enough to fulfill their function 


═══ 6. In case of troubles ═══

What to do if you have troubles with FBiMon.sys 

There are two kind of bugs : 

     The first one is my favorite... but will not be yours !!! It happens when 
      you can read the infamous screen telling you the system has crashed and 
      showing lots of information about registers. It is my favorite since this 
      kind of bugs can be quickly eliminated due to the help of information. I 
      sincerely apologize if this happens to you. By the way, it would be very 
      kind to send me the entire screen. If it can reassure you, I do not count 
      this kind of crash anymore. 
     The second one is more... annoying for me, but you should enjoy it much 
      more than the previous bug ! For some reasons, an application using the 
      driver could crash or the driver would not work as stated in this 
      documentation. If this happens to you, please tell me in which situation 
      the more precisely you can, and I will try to fix it. 


═══ 7. Developper's side ═══

This section is reserved to people who wants to use the FBiMon driver for 
development 


═══ 7.1. Driver function's OpCodes ═══

I have followed some conventions when writing this section. First, Every number 
starting with '0x' is written in hexadecimal notation. Next, I used a graphic 
representation of bytes sequences needed to execute the functions like this one 
: 

                         ┌ ── ┬ ── ┬ ── ┬ ── ┬ ── ┬ ── ┐
                         │ XX │ YY │ ZZ │ TT │ UU │ VV │
                         └ ── ┴ ── ┴ ── ┴ ── ┴ ── ┴ ── ┘

every 'XX', 'YY'... is explained just below this array. The first two bytes are 
always the command OpCode. Bytes are written according to the sequence used by 
Intel microprocessors. One cell is always one byte. 

There are only up to 16 reserved function opcode, some are already implemented, 
some are not. I plan to make this list growing up. 

 OpCodes        Meaning 
 0x0001         Set Text/Graphics mode 
 0x0002         Set default text attributes 
 0x0003         Set active/inactive blinking 
 0x0004         Set text cursor aspect 
 0x0005         Scroll the screen in all directions (not yet implemented) 
 0x0006         Set Start Address of video memory (not yet implemented) 
 0x0007         Print text with default attributes 
 0x0008         Print text with given attributes (not yet implemented) 
 0x0009         Set text cursor position 
 0x000A         Draw a pixel 
 0x000B         Draw a line (not yet implemented) 
 0x000C         Draw a horizontal line 
 0x000D         Draw a vertical line 
 0x000E         Draw a rectangle (not yet implemented) 
 0x000F         Fill a rectangle zone (not yet implemented) 
 0x0010         Invert a rectangle zone (not yet implemented) 


═══ 7.1.1. Set Text/Graphics mode ═══

This OpCode takes only one parameter 

┌──┬──┬──┐
│01│00│XX│
└──┴──┴──┘
XX values : 

 Value     Meaning 
 0x00      Set Text mode 
 0x01      Set Graphic mode 

 This function initializes the Hercules Graphic Card to the desired mode, 
 clears the screen and resets text attributes to default. 

 Mode                Technical info 
 Text                80 columns for 25 rows, text only with attributes like 
                     blink, underline, high or low intensity, character matrix 
                     is 9x14. 
 Graphic             720 columns for 348 rows, graphic only, only black and 
                     white colors are available. 


═══ 7.1.2. Set default text attributes ═══

This OpCode takes only one parameter 

┌──┬──┬──┐
│02│00│XX│
└──┴──┴──┘
XX values are explained in this table 

This function sets the text attributes used in text mode when printing a 
string. It is meaningless when using graphic mode. 


═══ 7.1.3. Set active/inactive blinking ═══

This OpCode takes only one parameter 

┌──┬──┬──┐
│03│00│XX│
└──┴──┴──┘
XX values : 

 Value     Meaning 
 0x00      Disable blink attribute 
 0x01      Enable blink attribute 

 This function allows you to control the effect of the attribute bit "blink". 
 It is meaningless when using graphic mode. 


═══ 7.1.4. Set text cursor aspect ═══

┌──┬──┬──┬──┬──┐
│04│00│FF│LL│XX│
└──┴──┴──┴──┴──┘
FF and LL value range is 0x00..0x1F (0..31). FF is the first scanline, and LL 
is the last scanline. 

XX values : 

 Value     Meaning 
 0x00      No blinking (for the cursor, not for the text) 
 0x01      Cursor is not displayed 
 0x02      Blinking with 16*refresh rate (for the cursor, not for the text) 
 0x03      Blinking with 32*refresh rate (for the cursor, not for the text) 

 This function allows you to set the size and shape of the hardware text 
 cursor. 

 Though values up to 0x1F (31) are allowed for FF and LL (the hardware supports 
 it), it is meaningless to use values higher than 0x0F (15). It is meaningless 
 when using graphic mode. 


═══ 7.1.5. Print text with default attributes ═══

┌──┬──┬──┬──┬──┬──┬──┬──┬───┐
│07│00│L1│L0│**│**│**│**│...│
└──┴──┴──┴──┴──┴──┴──┴──┴───┘

L0L1 is a word containing the length of the **** string. 

This function prints the **** string on screen in text mode at the current 
screen position (see Set text cursor position) and with the current text 
attributes (see Set default text attributes). It is meaningless when using 
graphic mode. 


═══ 7.1.6. Set text cursor position ═══

┌──┬──┬──┬──┬──┬──┐
│09│00│X1│X0│Y1│Y0│
└──┴──┴──┴──┴──┴──┘

X0X1 and Y0Y1 are the two words defining the new desired position for the text 
cursor. X0X1 is the column index (range=0..79), and Y0Y1 is the row index 
(range=0..24). 

This function defines the current text position where will begin to display 
next string, and also defines the position of the hardware text cursor on the 
screen. 


═══ 7.1.7. Draw a pixel ═══

┌──┬──┬──┬──┬──┬──┬──┐
│0A│00│X1│X0│Y1│Y0│CC│
└──┴──┴──┴──┴──┴──┴──┘

X0X1 and Y0Y1 are the two words defining the desired position for the pixel to 
be drawn. X0X1 is the column index (range=0..719), and Y0Y1 is the row index 
(range=0..347). 

CC values : 

 Value     Meaning 
 0x00      Clear pixel 
 0x01      Draw Pixel 
 0x02      Invert pixel (not yet implemented) 

 This function is meaningless for text mode. 


═══ 7.1.8. Draw a horizontal line ═══

┌──┬──┬──┬──┬──┬──┬──┬──┬──┐
│0C│00│W1│W0│X1│X0│Y1│Y0│CC│
└──┴──┴──┴──┴──┴──┴──┴──┴──┘

This function draws a horizontal line from (W0W1,Y0Y1) to (X0X1,Y0Y1) using 
color CC. W0W1, X0X1 range is 0..719 and Y0Y1 range is 0..347. 

CC values : 

 Value     Meaning 
 0x00      Clear pixel 
 0x01      Draw Pixel 
 0x02      Invert pixel (not yet implemented) 

 This function is meaningless for text mode. 


═══ 7.1.9. Draw a vertical line ═══

┌──┬──┬──┬──┬──┬──┬──┬──┬──┐
│0D│00│X1│X0│Y1│Y0│Z1│Z0│CC│
└──┴──┴──┴──┴──┴──┴──┴──┴──┘

This function draws a vertical line from (X0X1,Y0Y1) to (X0X1,Z0Z1) using color 
CC. W0W1, X0X1 range is 0..719 and Y0Y1 range is 0..347. 

CC values : 

 Value     Meaning 
 0x00      Clear pixel 
 0x01      Draw Pixel 
 0x02      Invert pixel (not yet implemented) 

 This function is meaningless for text mode. 


═══ 7.2. Text Attributes ═══

 Attribute Meaning 
 0x00      Show nothing (character is not drawn) 
 0x01      Underline character 
 0x07      Low intensity 
 0x70      Invert background and foreground color 
 0x08      High intensity 
 0x80      Make the character blink